# 命令行工具

Rsbuild 内置了一个轻量的命令行工具，包含 [rsbuild dev](#rsbuild-dev)、[rsbuild build](#rsbuild-build) 等命令。

## rsbuild -h

如果你需要查看所有可用的 CLI 命令，请在项目目录中运行以下命令：

```bash
npx rsbuild -h
```

输出如下：

```text
Usage: rsbuild <command> [options]

Options:
  -V, --version      显示版本号
  -h, --help         显示命令帮助

Commands:
  dev [options]      启动开发服务器
  build [options]    构建生产环境产物
  preview [options]  本地预览生产环境产物
  inspect [options]  检查 Rspack 和 Rsbuild 配置
  help [command]     显示命令帮助
```

## rsbuild dev

`rsbuild dev` 命令用于启动一个本地开发服务器，对源代码进行开发模式编译。

```bash
Usage: rsbuild dev [options]

Options:
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  -r --root <root>      指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
  -m --mode <mode>      指定构建模式，可以是 `development`，`production` 或 `none`
  -o, --open [url]      启动时是否在浏览器中打开页面
  --port <port>         设置 Rsbuild Server 监听的端口号
  --host <host>         指定 Rsbuild Server 启动时监听的 host
  --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
  --env-dir <dir>       指定目录来加载 `.env` 文件
  --environment <name>  指定需要构建的 environment 名称
  -h, --help            显示命令帮助
```

### 打开页面

通过 `--open` 选项可以在启动 dev server 时自动打开页面，等同于将 [server.open](/config/server/open) 设置为 `true`。

```bash
rsbuild dev --open
```

`--open` 选项也支持指定需要打开的 URL 地址，比如：

```bash
rsbuild dev --open http://localhost:3000/foo
```

`--open` 选项也可以缩写为 `-o`：

```bash
rsbuild dev -o
```

:::tip
当同时使用 [server.open](/config/server/open) 和 `--open` 时，`--open` 的优先级更高。
:::

## rsbuild build

`rsbuild build` 命令默认会在 `dist/` 目录下构建出可用于生产环境的产物。

```bash
Usage: rsbuild build [options]

Options:
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  -r --root <root>      指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
  -m --mode <mode>      指定构建模式，可以是 `development`，`production` 或 `none`
  -w --watch            开启 watch 模式, 监听文件变更并重新构建
  --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
  --env-dir <dir>       指定目录来加载 `.env` 文件
  --environment <name>  指定需要构建的 environment 名称
  -h, --help            显示命令帮助
```

## rsbuild preview

`rsbuild preview` 命令用于在本地预览生产模式构建的产物, 注意你需要提前执行 `rsbuild build` 命令构建出对应产物。

```bash
Usage: rsbuild preview [options]

Options:
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  -r --root <root>      指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
  -m --mode <mode>      指定构建模式，可以是 `development`，`production` 或 `none`
  -o, --open [url]      启动时是否在浏览器中打开页面
  --port <port>         设置 Rsbuild Server 监听的端口号
  --host <host>         指定 Rsbuild Server 启动时监听的 host
  --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
  --env-dir <dir>       指定目录来加载 `.env` 文件
  --environment <name>  指定需要构建的 environment 名称
  -h, --help            显示命令帮助
```

:::tip
preview 命令仅用于本地预览，请勿将它用于生产服务器，因为它不是为此而设计的。
:::

## rsbuild inspect

`rsbuild inspect` 命令用于查看项目的 Rsbuild 配置以及 Rspack 配置。

```bash
Usage: rsbuild inspect [options]

Options:
  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
  -r --root <root>      指定项目根目录，可以是绝对路径或者相对于 cwd 的路径
  -m --mode <mode>      指定构建模式，可以是 `development`，`production` 或 `none`
  --output <output>     指定在 dist 目录下输出的路径 (default: ".rsbuild")
  --verbose             在结果中展示函数的完整内容
  --env-mode <mode>     指定 env 模式来加载 `.env.[mode]` 文件
  --env-dir <dir>       指定目录来加载 `.env` 文件
  --environment <name>  指定需要构建的 environment 名称
  -h, --help            显示命令帮助
```

当你在项目根目录下执行命令 `npx rsbuild inspect` 后，会在项目的 `dist/.rsbuild` 目录生成以下文件：

- `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
- `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。

```bash
➜ npx rsbuild inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs
  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
```

### 指定模式

默认情况下，inspect 命令会输出开发模式的配置，你可以添加 `--mode production` 选项来输出生产模式的配置：

```bash
rsbuild inspect --mode production
```

### 完整内容

默认情况下，inspect 命令会省略配置对象中的函数内容，你可以添加 `--verbose` 选项来输出函数的完整内容：

```bash
rsbuild inspect --verbose
```

### 多种产物类型

如果当前项目有多种产物类型，比如同时构建了浏览器产物和 Node.js 产物，那么会在 `dist/.rsbuild` 目录生成多份 Rspack 配置文件。

```bash
➜ npx rsbuild inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs
  - Rsbuild Config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs
  - Rspack Config (web): /project/dist/.rsbuild/rspack.config.web.mjs
  - Rspack Config (node): /project/dist/.rsbuild/rspack.config.node.mjs
```
